Amiga Developer CD 2.1

home *** CD-ROM | disk | FTP | other *** search

/ Amiga Developer CD 2.1 / Amiga Developer CD v2.1.iso / Contributions / Olaf_Barthel / Tools / AmigaGuide / CheckGuide / CheckGuide.doc < prev next >

Wrap

Text File | 1997-08-21 | 13.5 KB | 389 lines

CheckGuide - A tool to check the consistency of AmigaGuide databases ==================================================================== Copyright © 1997 by Olaf Barthel <olsen@sourcery.han.de> All Rights Reserved 1. What this program does ------------------------- Authoring AmigaGuide files is easy; the difficult part is to produce consistent databases AmigaGuide will display correctly and which don't contain unused nodes, references to undefined nodes, syntax errors and other troubles that are really difficult to spot. The original AmigaGuide was rewritten for Workbench 3.0 where it was implemented as a datatypes class. As it turned out, the new implementation behaved differently. This was caused by the introduction of the backslash ("\") as an escape character and a different parser which was less tolerant. The big problem of AmigaGuide is that it has no strict syntax definition. Nobody really seems to know when and where a backslash has its effects. Also, AmigaGuide does not detect errors in the documents it reads. It may behave unpredictably, but no errors are reported. CheckGuide does a number of consistency checks on the databases and reports them. Some of the problems reported really count as warnings, AmigaGuide will still process and display the document, but may behave in an unpredictable way. Other problems reported really belong into the realm of "style". See for yourself. 2. What this program does not ----------------------------- As no strict syntax definition of the AmigaGuide "language" exists and there is no complete list of keywords which AmigaGuide understands, CheckGuide cannot find all possible problems. An AmigaGuide file may still count as "correct" if it fails any of the tests CheckGuide makes, because as a last resort, the actual AmigaGuide implementation defines compliance. A specific problem is in the treatment of the escape character ("\") which due to incomplete documentation is not always treated the same way as AmigaGuide treats it. 3. Starting the program ----------------------- CheckGuide takes any number of arguments, each of which must refer to the name of a file to read and check. The following options are supported: -r, --recursive CheckGuide will operate in recursive mode, which means that if a link to a file is found, CheckGuide will proceed to follow this link and check the file. When following links, each file is checked exactly once, so no processing time is wasted or circular dependencies crop up. -o, --onlyguidefiles This works in conjunction with the -r option: when following a link, CheckGuide will silently stop processing any file that does not qualify as an AmigaGuide database (i.e. if it does not have the @DATABASE keyword in the first line). -w, --nowarnings This option suppresses reporting of problems that do not really count as errors. 4. Errors reported ------------------ The following list explains what error messages CheckGuide produces and what they mean. As said before, some of the messages really count as warnings only. 4.1. Buttons ------------ By default, AmigaGuide displays hyperlinks as buttons (although the appearance is configurable). These buttons are declared using a common syntax like this: @{<Label> (Command) (Parameters)} Some commands take additional parameters (such as the "LINK" command), while some do not (such as the "QUIT" command). Messages: Unknown link command <Name> The command specified for the button is not recognized. Known commands include LINK, ALINK, CLOSE, RX, RXS, SYSTEM and QUIT. Missing closing brace in button declaration Unbalanced open brace in button declaration Button declarations cannot span multiple lines, which means that the closing brace has to be on the same line as the "@{" token that introduces the link. Missing quote in button declaration The button label must be enclosed in quotes. With some of the commands you need to enclose the parameters in quotes. If the quotes are unbalanced, AmigaGuide may fail to parse the remainder of the line correctly. Incomplete/invalid link declaration The original AmigaGuide V34 would tolerate button declarations which had blank spaces between the @ character and the open brace (as in "@ {"). However, AmigaGuide V39 and up no longer recognize this syntax. Button label <Text> must be enclosed in quotes The label of each button must be enclosed in quotes, even if it includes no blank space characters. If the quotes are missing, AmigaGuide V40 will start throwing Enforcer hits. 4.1.1. Link commands -------------------- Links are declared with the following commands: @{<Label> LINK <Node or file> [Line number]} @{<Label> ALINK <Node or file> [Line number]} The line numbers may be omitted. The first parameter must refer to a node; AmigaGuide will always try to find the node in the current database and then attempt to open a file bearing the node name. If this happens, the given name is assumed to consist of a document name and a node name, like this: foo:bar/baz/MAIN In this example "foo:bar/baz" is the name of the file to open and "MAIN" is the node to display. "MAIN" is the general catchall, i.e. links to non-AmigaGuide-files can be established only if the node name is "MAIN". Otherwise, AmigaGuide will complain about being unable to open the file. The same happens if the node name is omitted, i.e. the plain file name is not sufficient to define a link. Messages: ALINK line number invalid LINK line number invalid The line number given is not a number but contains alphanumeric characters. ALINK node name required LINK node name required The node or file name parameter has been omitted. File found in relative path only <Name> You can create links to other files which AmigaGuide will load and display instead of the database you originally started from. The current implementation of AmigaGuide (V40) tries to open files pointed to by links by the names given. Thus, a file name "foo/bar/baz/MAIN" will cause the file "foo/bar/baz" to be opened, relative to the current directory of the AmigaGuide program. This directory may not be the same as the directory the file you originally started from is found in. Naturally, this can cause some confusion as AmigaGuide may complain about being unable to open a file a link points to. Generally, it is safer to use absolute paths instead (as in "foo:bar/baz/MAIN"), but this approach has its own risks and disadvantages. Reference to undefined node <Name> The file or node a link refers to is neither found in the current document nor on the filing system. CheckGuide tries to interprete file names relative to the name of the database it checks, but even that can fail if files are simply not there. AmigaGuide also uses an environment variable "PATH" to locate nodes. CheckGuide does not support this feature. And really, you should not depend on it in your databases. 4.1.2. ARexx and AmigaDOS commands ---------------------------------- ARexx and AmigaDOS commands are declared with the following commands: @{<Label> RX <Command>} @{<Label> RXS <Command>} @{<Label> SYSTEM <Command>} Messages: RX command required RXS command required SYSTEM command required The required command parameter was omitted. 4.1.3. Shutdown commands ------------------------ Shutdown commands include CLOSE and QUIT: @{<Label> CLOSE} @{<Label> QUIT} Messages: Too many arguments for CLOSE command Too many arguments for QUIT command Neither command takes any parameters. 4.2. Commands ------------- AmigaGuide recognizes a database it understands by a command found in the first line of the file. Other commands are used to convey information (such as copyrights, version numbers, etc.) and to provide structure (such as the node declarations). Commands are introduced by the @ character. Messages: Command <Name> has no effect A command such as @DATABASE must be placed in the first column of a line for AmigaGuide to recognize it. If it shows up anywhere else in the line, AmigaGuide will show it as plain text, which is probably not what you want. The first line must contain the @DATABASE keyword An AmigaGuide database must begin with the @DATABASE command in its first line for AmigaGuide to recognize it as such. MAIN node missing An AmigaGuide database has to contain at least one single node, the MAIN node. Unknown keyword <Name> An unknown command was found at the beginning of a line. 4.3. Nodes ---------- An AmigaGuide database consists of a set of so-called nodes. At least one node has to be defined, the MAIN node. Nodes are defined with the @NODE and @ENDNODE commands. Messages: Duplicate @NODE <Name> (see line <Number>) You assigned the same name to more than one node. As the name is no longer unique (note: case does not matter), AmigaGuide may display either one when you move to it. Which one is displayed is subject to undefined behaviour. The line number displayed in this error message refers to the first line in which a node with the given name is declared. Unbalanced @ENDNODE Each @NODE declaration has to be matched by exactly one @ENDNODE command. Here an unused @ENDNODE command has been found. Unbalanced @NODE Each @NODE declaration has to be matched by exactly one @ENDNODE command. Here an unterminated @NODE command has been found. Unused @NODE <Name> This is an indication of a node that has been declared but has no links from this file to it. This may be exactly what you want if these nodes are referred to from other AmigaGuide databases only. 4.4. Table of contents, index and browsing ------------------------------------------ For each node you may declare the name of the node that should be displayed when the "Contents" and "Index" buttons are pressed. Messages: INDEX node <Name> missing TOC node <Name> missing The node you specified with the @INDEX/@TOC command could not be found. More than one @INDEX at top level More than one @TOC at top level While no node is currently being defined you can still declare the names of the @INDEX and @TOC nodes valid for the remainder of the document. Normally, these should be declared before any other nodes are defined. And there better be only a single declaration of these. @NEXT references undefined node <Name> @PREV references undefined node <Name> The two browsing commands must of course refer to existing nodes. 4.5. Text colour and style -------------------------- AmigaGuide V39 introduced control commands for text colour and style. Like buttons, these can appear anywhere in the text. The control commands look like this: @{fg text} @{bg shine} @{b} @{ub} Messages: Invalid colour control string <Name> Invalid colour <Name> The colour specified with the @{fg } and @{bg } commands is not known. Known colours include TEXT, SHINE, SHADOW, FILL, FILLTEXT, BACK and HIGHLIGHT. Unbalanced <Command> in column <Number> Text style commands should be balanced, e.g. @{u} should be followed by @{uu} somewhere down the text. Command <Command> in column <Number> has no effect Turning off a text style command (e.g. @{ub}) while it is already turned off will have no noticeable effect. 4.6. Style ---------- The following messages deal with the @DATABASE command at the beginning of each AmigaGuide file and the file name. Messages: Database <Name> and file name <Name> do not match Database and file name should be identical. Database <Suffix> and file name <Suffix> suffixes do not match The file name suffixes (.guide) are not identical, they might even have been omitted. Database name <Name> contains path specifiers The @database name should only contain the base name of the file. Database name uses obsolete .hyper suffix File uses obsolete .hyper name suffix The original AmigaGuide specs defined that each database name should have the suffix ".hyper" appended. This was changed later to ".guide". 4.7. Escape characters ---------------------- CheckGuide reports when and where the escape character "\" is used. You may want to check these locations yourself as consistency checks on this construct are beyond the scope of this program. The same holds true for the use of the "@" character which can be escaped with another "@". CheckGuide also warns you when it encounters single "@" and "\" characters that don't seem to belong to a command or control sequence. 4.8. Other messages ------------------- In addition to the errors listed above, CheckGuide also performs consistency checks on command parameters which will be reported with AmigaDOS error messages. 5. Implementation ----------------- Don't expect documentation, CheckGuide grew out of a ten minute hack I wrote in order to find errors in the CygnusEd online documentation, and the source code still shows. CheckGuide does two passes on the document; the first to collect node names and the second to match them with link commands. During both passes CheckGuide attempts to detect and report defects. The net effect being that the error messages it produces are not necessarily in ascending line number order. The keyword tests are not complete. I tried to collect all known keywords AmigaGuide understands, but hit a brick wall since they are so poorly documented. While I am determined to retain the rights to this software, don't let that put you off. Enhancement requests and improvements to the actual implementation are always welcome. 6. Conclusions -------------- As testing with CheckGuide revealed, the majority of AmigaGuide databases have severe defects. I guess CheckGuide was badly necessary.